Skip to content

docs: add 'Using witr with AI Agents' section - #224

Closed
yunaremaia wants to merge 2 commits into
pranshuparmar:mainfrom
yunaremaia:docs/ai-agents-section-223
Closed

docs: add 'Using witr with AI Agents' section#224
yunaremaia wants to merge 2 commits into
pranshuparmar:mainfrom
yunaremaia:docs/ai-agents-section-223

Conversation

@yunaremaia

@yunaremaia yunaremaia commented Aug 9, 2026

Copy link
Copy Markdown

Closes #223

Problem

AI coding agents (Claude Code, Codex, Cursor) constantly hit port-in-use, zombie servers, and container confusion during local dev — and chain lsof/ps/netstat/docker ps manually. witr already fixes this via --json, but the README never mentions it, so agents (and humans) don't discover it.

Changes

Add Section 8 — Using witr with AI Agents to README.md:

  • States that --json is the machine-output flag (single parseable line; exit codes already scriptable).
  • AGENTS.md / CLAUDE.md snippet: port conflict (witr --port <PORT> --json), stuck process (witr <name> --json / witr --pid <PID> --tree), container (witr --container <name> --verbose --json).
  • Optional Claude Code slash command (.claude/commands/witr.md).
  • Short rationale for no MCP wrapper: agents already have shell access; --json is the one-line structured call.
  • Renumbered sections 9–11 (Platform Support, Success Criteria, Sponsors).

Verification

  • git diff --check clean.
  • Anchor #72-exit-codes verified against existing ### 7.2 Exit Codes heading.

@yunaremaia
docs: add 'Using witr with AI Agents' section
47f52e1 
AI coding agents hit port-in-use, zombie servers and container confusion
during local dev; they chain lsof/ps/netstat/docker ps manually. witr
already fixes this via --json but the README never said so.

Add section 8 with an AGENTS.md/CLAUDE.md snippet (port, process, and
container queries with --json), an optional Claude Code slash command, and
a short rationale for not wrapping witr in MCP (shell access + --json is
already the one-line structured call). Renumber sections 9-11.

Signed-off-by: Yunare Maia <yunare@gmail.com>
@yunaremaia yunaremaia mentioned this pull request Aug 9, 2026
Open
@lets-build-an-ocean

lets-build-an-ocean commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Hey @yunaremaia 👋🏻

Thanks for putting this together; I think it's a solid direction overall, but a few things to fix up:

  1. Numbering order in the README
    The section numbers are out of sequence — right now it goes 9. Platform Support before 8.1 Feature Compatibility Matrix. Could you fix the ordering so the sections flow correctly?

  2. Two sections we can drop

Claude Code slash command (optional)
Why not an MCP wrapper?

Neither adds much value here, so I'd suggest removing both to keep things focused.

  1. Expand the .md snippet instead
    Rather than the above, I think a more detailed .md snippet would help a lot more. That said, it doesn't need to be exhaustive — since agents can just run --help to figure out what witr does, we mainly need enough to point them in the right direction, not full documentation.

Can you:

Fix the numbering in the README
Share an updated, slightly more comprehensive .md snippet here in the thread (doesn't need to be long)

Thanks again for the work on this!

@yunaremaia
docs: address review — drop 2 sections, expand .md snippet, fix numbe…
f378f3e 
…ring

Per maintainer review (#224):
- Remove 'Claude Code slash command (optional)' and 'Why not an MCP wrapper?'
- Expand the AGENTS.md/CLAUDE.md snippet with the structured output contract
  (--json shape, exit codes incl. 2 = no match, --help pointer)
- Renumber: 8.1 Feature Compatibility Matrix -> 9.1 (Platform Support is now 9)

Signed-off-by: Yunare Maia <yunare@gmail.com>
@yunaremaia

yunaremaia commented Aug 11, 2026

Copy link
Copy Markdown
Author

All three review points addressed — pushed (f378f3e):

  1. Numbering fixed — the section flow is now clean: 8. Using witr with AI Agents → 9. Platform Support → 9.1 Feature Compatibility Matrix → 10. Success Criteria → 11. Sponsors. The stale 8.1 sub-numbering was the culprit.

  2. Dropped both sections — "Claude Code slash command (optional)" and "Why not an MCP wrapper?" are removed.

  3. Expanded the .md snippet — the AGENTS.md/CLAUDE.md snippet now also describes the machine contract agents rely on: --json emits one structured line (process tree, resolved cause, warnings), exit code 2 signals "no match found" so agents can branch without parsing prose, and witr --help covers the rest. Kept it concise per your note — it points agents in the right direction without duplicating the CLI reference.

Thanks for the thorough review!

@yunaremaia yunaremaia closed this by deleting the head repository Aug 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Docs] Add "Using witr with AI coding agents" section (Claude Code, Codex, etc.)

2 participants

@yunaremaia @lets-build-an-ocean